<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>WinTitle &amp; Last Found Window</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
  <link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<style type="text/css">
#QuickRef {
  border: 1px solid #ccc;
  margin: 1em;
  border-spacing: 0;
}
#QuickRef a {
  padding-left: 1em;
}
#QuickRef td {
  padding: .2em .5em;
}
#QuickRef tr:nth-child(even) {
  background-color: #f4f4f4;
}
</style>
</head>
<body>
<h1>The <em>WinTitle</em> Parameter &amp; the Last Found Window</h1>

<p>Many commands and a few functions have a <em>WinTitle</em> parameter, used to identify which window (or windows) to operate on. This parameter can be the title or partial title of the window, and/or any other criteria described on this page.</p>

<strong>Quick Reference:</strong>
<table id="QuickRef">
  <tr><td><em>Title</em></td><td><a href="#Matching">Matching Behaviour</a></td></tr>
  <tr><td>A</td><td><a href="#ActiveWindow">The Active Window</a></td></tr>
  <tr><td>ahk_class</td><td><a href="#ahk_class">Window Class</a></td></tr>
  <tr><td>ahk_id</td><td><a href="#ahk_id">Unique ID/HWND</a></td></tr>
  <tr><td>ahk_pid</td><td><a href="#ahk_pid">Process ID</a></td></tr>
  <tr><td>ahk_exe</td><td><a href="#ahk_exe">Process Name/Path</a></td></tr>
  <tr><td>ahk_group</td><td><a href="#ahk_group">Window Group</a></td></tr>
  <tr><td>&nbsp;</td><td><a href="#multi">Multiple Criteria</a></td></tr>
  <tr><td>(All empty)</td><td><a href="#LastFoundWindow">Last Found Window</a></td></tr>
</table>

<h2 id="Matching">Matching Behaviour</h2>
<p><a href="../commands/SetTitleMatchMode.htm">SetTitleMatchMode</a> controls how a partial or complete title is compared against the title of each window. Depending on the setting, <em>WinTitle</em> can be an exact title, or it can contain a prefix, a substring which occurs anywhere in the title, or a <a href="RegEx-QuickRef.htm">RegEx pattern</a>. This setting also controls whether <a href="#ahk_class">ahk_class</a> is interpreted as an exact class name or a RegEx pattern.</p>
<p>Hidden windows are only detected if <a href="../commands/DetectHiddenWindows.htm">DetectHiddenWindows</a> is On, except with <a href="../commands/WinShow.htm">WinShow</a>, which always detects hidden windows.</p>
<p>If multiple windows match the <em>WinTitle</em> and any other criteria, the topmost matching window is used. If the active window matches the criteria, it usually takes precedence since it is usually above all other windows. However, if an <a href="../commands/WinSet.htm#AlwaysOnTop">always-on-top</a> window also matches (and the active window is not always-on-top), it may be used instead.</p>

<h2 id="ActiveWindow">Active Window (A)</h2>
<p>If <em>WinTitle</em> is the letter <code>A</code> and the other 3 window parameters (<em>WinText</em>, <em>ExcludeTitle</em> and <em>ExcludeText</em>) are blank or omitted, the active window will be used.</p>
<pre>
<em>; Retrieve the ID/HWND of the active window</em>
id := WinExist("A")
MsgBox % id

<em>; Press Win+&uarr; to maximize the active window</em>
#Up::WinMaximize, A</pre>

<h2 id="ahk_class">ahk_class Window Class</h2>
<p>A window class is a set of attributes that the system uses as a template to create a window. In other words, the class name of the window identifies what <em>type</em> of window it is. To use a window class, specify <code>ahk_class ExactClassName</code> as shown by Window Spy. <em>ExactClassName</em> can be retrieved by <a href="../commands/WinGetClass.htm">WinGetClass</a>.</p>
<p>If the RegEx <a href="../commands/SetTitleMatchMode.htm">title matching mode</a> is active, ahk_class accepts a <a href="../misc/RegEx-QuickRef.htm">regular expression</a>.</p>
<pre>
<em>; Activate a console window (e.g. cmd.exe)</em>
WinActivate, ahk_class ConsoleWindowClass
</pre>

<h2 id="ahk_id">ahk_id Unique ID / HWND</h2>
<p>Each window or control has a unique ID, also known as a HWND (short for handle to window). This ID can be used to identify the window or control even if its title changes. The ID of a window is typically retrieved via <a href="../commands/WinExist.htm">WinExist()</a> or <a href="../commands/WinGet.htm">WinGet</a>. The ID of a control is typically retrieved via <a href="../commands/ControlGet.htm#Hwnd">ControlGet Hwnd</a>, <a href="../commands/MouseGetPos.htm">MouseGetPos</a>, or <a href="../commands/DllCall.htm">DllCall</a>. Also, ahk_id will operate on controls even if they are hidden; that is, the setting of <a href="../commands/DetectHiddenWindows.htm">DetectHiddenWindows</a> does not matter for controls.</p>
<pre>
WinActivate, ahk_id %VarContainingID%
</pre>

<h2 id="ahk_pid">ahk_pid Process ID</h2>
<p>Use ahk_pid to identify a window belonging to a specific process. The process identifier (PID) is typically retrieved by <a href="../commands/WinGet.htm">WinGet</a>, <a href="../commands/Run.htm">Run</a> or <a href="../commands/Process.htm">Process</a>.</p>
<pre>
WinActivate, ahk_pid %VarContainingPID%
</pre>

<h2 id="ahk_exe">ahk_exe Process Name/Path <span class="ver">[v1.1.01+]</span></h2>
<p>Use ahk_exe to identify a window belonging to any process with the given name or path.</p>
<p>While <a href="#ahk_pid">ahk_pid</a> is limited to one specific process, ahk_exe considers all processes with name or full path matching a given string. If the RegEx <a href="../commands/SetTitleMatchMode.htm">title matching mode</a> is active, ahk_exe accepts a <a href="../misc/RegEx-QuickRef.htm">regular expression</a>. Otherwise, ahk_exe accepts a case-insensitive name or full path; for example, <code>ahk_exe notepad.exe</code> covers <code>ahk_exe C:\Windows\Notepad.exe</code>, <code>ahk_exe C:\Windows\System32\Notepad.exe</code> and other variations.</p>
<pre>
<em>; Activate an existing notepad.exe window, or open a new one</em>
if WinExist("ahk_exe notepad.exe")
    WinActivate, ahk_exe notepad.exe
else
    Run, notepad.exe
</pre>

<h2 id="ahk_group">ahk_group Window Group</h2>
<p>Use ahk_group to identify a window or windows matching the rules contained by a previously defined <a href="../commands/GroupAdd.htm">window group</a>.</p>
<p>The commands <a href="../commands/WinMinimize.htm">WinMinimize</a>, <a href="../commands/WinMaximize.htm">WinMaximize</a>, <a href="../commands/WinRestore.htm">WinRestore</a>, <a href="../commands/WinHide.htm">WinHide</a>, <a href="../commands/WinShow.htm">WinShow</a>, <a href="../commands/WinClose.htm">WinClose</a>, and <a href="../commands/WinKill.htm">WinKill</a> will act on <strong>all</strong> the group's windows. By contrast, the other window commands such as <a href="../commands/WinActivate.htm">WinActivate</a> and <a href="../commands/WinExist.htm">IfWinExist</a> will operate only on the topmost window of the group.</p>
<pre>
<em>; Define the group: Windows Explorer windows</em>
GroupAdd, Explorer, ahk_class ExploreWClass <em>; Unused on Vista and later</em>
GroupAdd, Explorer, ahk_class CabinetWClass

<em>; Activate any window matching the above criteria</em>
WinActivate, ahk_group Explorer
</pre>

<h2 id="multi">Multiple Criteria</h2>
<p>By contrast with <a href="#ahk_group">ahk_group</a> (which broadens the search), the search may be narrowed by specifying more than one criterion within the WinTitle parameter. In the following example, the script waits for a window whose title contains <em>My File.txt</em> <strong>and</strong> whose class is <em>Notepad</em>:</p>
<pre>WinWait <strong>My File.txt</strong> ahk_class <strong>Notepad</strong>
WinActivate  <em>; Activate the window it found.</em></pre>
<p>When using this method, the text of the title (if any is desired) should be listed first, followed by one or more additional criteria. Criteria beyond the first should be separated from the previous with exactly one space or tab (any other spaces or tabs are treated as a literal part of the previous criterion).</p>
<p><a href="#ahk_id">ahk_id</a> can be combined with other criteria to test a window's title, class or other attributes:</p>
<pre>
MouseGetPos,,, id
if WinExist("ahk_class Notepad ahk_id " id)
    MsgBox The mouse is over Notepad.
</pre>


<h2 id="LastFoundWindow">The &quot;Last Found&quot; Window</h2>

<p>This is the window most recently found by <a href="../commands/WinExist.htm">IfWin[Not]Exist</a>, <a href="../commands/WinExist.htm">WinExist()</a>, <a href="../commands/WinActive.htm">IfWin[Not]Active</a>, <a href="../commands/WinActive.htm">WinActive()</a>, <a href="../commands/WinWaitActive.htm">WinWait[Not]Active</a>, or <a href="../commands/WinWait.htm">WinWait</a>. It can make scripts easier to create and maintain since the WinTitle and WinText of the target window do not need to be repeated for every windowing command. In addition, scripts perform better  because they don't need to search for the target window again after it has been found the first time.</p>
<p>The &quot;last found&quot; window can be used by all of the windowing commands except <a href="../commands/WinWait.htm">WinWait</a>, <a href="../commands/WinActivateBottom.htm">WinActivateBottom</a>, and <a href="../commands/GroupAdd.htm">GroupAdd</a>. To use it, simply omit all four window parameters (WinTitle, WinText, ExcludeTitle, and ExcludeText).</p>
<p>Each <a href="../misc/Threads.htm">thread</a> retains its own value of the &quot;last found&quot; window, meaning that if the <a href="../misc/Threads.htm">current thread</a> is interrupted by another, when the original thread is resumed it will still have its original value of the &quot;last found&quot; window, not that of the interrupting thread.</p>
<p>If the last found window is a hidden <a href="../commands/Gui.htm">Gui window</a>, it can be used even when <a href="../commands/DetectHiddenWindows.htm">DetectHiddenWindows</a> is Off. This is often used in conjunction with <code><a href="../commands/Gui.htm#LastFound">Gui +LastFound</a></code>.</p>
<pre class="NoIndent">Run Notepad
WinWait Untitled - Notepad
WinActivate  <em>; Uses the last found window.</em>

IfWinExist, Untitled - Notepad
{
    WinActivate  <em>; Automatically uses the window found above.</em>
    WinMaximize  <em>; same</em>
    Send, Some text.{Enter}
    return
}

IfWinNotExist, Calculator
    return
else
{
    WinActivate  <em>; The above &quot;IfWinNotExist&quot; also set the &quot;last found&quot; window for us.</em>
    WinMove, 40, 40  <em>; Move it to a new position.</em>
    return
}</pre>

</body>
</html>
